Feature: Key Management Service (KMS) by vishesh92 · Pull Request #12711 · apache/cloudstack

vishesh92 · 2026-02-26T06:20:32Z

Key Management Service (KMS) with HSM Integration

Description

Introduces a Key Management Service (KMS) framework for CloudStack that provides envelope encryption for volume encryption. KEKs (Key Encryption Keys) stored in PKCS#11-compliant HSMs or the CloudStack database wrap per-volume DEKs (Data Encryption Keys), ensuring key material is never stored in plaintext.

Design Document: https://cwiki.apache.org/confluence/display/CLOUDSTACK/Key+Management+Service+%28KMS%29+with+HSM+Integration
Docs PR: #12711

New APIs

API	Auth	Description
`createKMSKey`	All users	Create a KMS key (KEK) bound to an HSM profile
`listKMSKeys`	All users	List KMS keys
`updateKMSKey`	All users	Update name, description, or enabled state
`deleteKMSKey`	All users	Delete a KMS key (if not in use)
`rotateKMSKey`	Admin	Rotate KEK with optional cross-HSM migration
`migrateVolumesToKMS`	Admin	Migrate passphrase-encrypted volumes to KMS
`addHSMProfile`	Admin	Add HSM profile configuration
`listHSMProfiles`	All users	List available HSM profiles
`updateHSMProfile`	Admin	Update HSM profile
`deleteHSMProfile`	Admin	Delete HSM profile

New Database Tables

kms_hsm_profiles, kms_hsm_profile_details, kms_keys, kms_kek_versions, kms_wrapped_key, kms_database_kek_objects

Modified: cloud.volumes — added kms_key_id and kms_wrapped_key_id columns.

New Global Settings

Setting	Default	Description
`kms.dek.size.bits`	`256`	DEK size in bits
`kms.retry.count`	`3`	Retry attempts for transient failures
`kms.retry.delay.ms`	`1000`	Delay between retries
`kms.operation.timeout.sec`	`30`	Per-operation timeout
`kms.rewrap.batch.size`	`50`	Keys rewrapped per background batch
`kms.rewrap.interval.ms`	`300000`	Background rewrap interval

UI Changes

New KMS top-level menu with KMS Keys and HSM Profiles sub-sections
KMS key selection in Deploy VM and Create Volume wizards
HSM profile management restricted to Admin users in UI

How to Test

Tested with:

# 1. Add an HSM profile (use SoftHSM2 for testing)

# 2. Create a KMS key with HSM profile

# 3. Create a disk offering with Encryption enabled

# 4. Deploy a VM/create a volume and specify the KMS key

codecov · 2026-02-26T07:12:27Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 3.51%. Comparing base (b744824) to head (b68661c).

❗ There is a different number of reports uploaded between BASE (b744824) and HEAD (b68661c). Click for more details.

HEAD has 1 upload less than BASE

Flag BASE (b744824) HEAD (b68661c)

unittests 1 0

Additional details and impacted files

@@              Coverage Diff              @@
##               main   #12711       +/-   ##
=============================================
- Coverage     18.02%    3.51%   -14.51%     
=============================================
  Files          5968      465     -5503     
  Lines        537086    40194   -496892     
  Branches      65961     7572    -58389     
=============================================
- Hits          96819     1414    -95405     
+ Misses       429347    38590   -390757     
+ Partials      10920      190    -10730

Flag	Coverage Δ
uitests	`3.51% <ø> (-0.02%)`	⬇️
unittests	`?`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

This pull request introduces a comprehensive Key Management Service (KMS) framework for CloudStack that provides envelope encryption for volume encryption. KEKs (Key Encryption Keys) stored in PKCS#11-compliant HSMs or the CloudStack database wrap per-volume DEKs (Data Encryption Keys), ensuring key material is never stored in plaintext.

Changes:

Adds KMS framework with HSM integration for envelope encryption
Introduces 8 new admin/user APIs for KMS key and HSM profile management
Creates 6 new database tables for storing KMS metadata
Adds UI support for KMS key selection in volume and VM deployment workflows

Reviewed changes

Copilot reviewed 123 out of 123 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`framework/kms/`	Core KMS framework interfaces and exceptions
`plugins/kms/`	Database and PKCS#11 KMS provider implementations
`engine/schema/`	Database entities and DAOs for KMS tables
`api/src/main/java/org/apache/cloudstack/api/command/`	New API commands for KMS operations
`ui/src/views/`	UI components for KMS key selection
`server/src/main/java/`	KMS manager implementation and integration
Test files	Unit tests for KMS retry logic and key creation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

blueorangutan · 2026-02-26T13:44:04Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16962

Copilot

Pull request overview

Copilot reviewed 124 out of 124 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tools/apidoc/gen_toc.py

engine/schema/src/main/java/com/cloud/storage/dao/VolumeDaoImpl.java

engine/storage/volume/src/main/java/org/apache/cloudstack/storage/volume/VolumeObject.java

server/src/main/java/com/cloud/api/query/dao/VolumeJoinDaoImpl.java

engine/schema/src/main/java/org/apache/cloudstack/kms/dao/KMSWrappedKeyDaoImpl.java

ui/src/views/compute/DeployVM.vue

server/src/main/java/com/cloud/api/ApiResponseHelper.java

vishesh92 · 2026-03-04T08:41:41Z

@blueorangutan package

blueorangutan · 2026-03-04T08:44:04Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-03-04T09:36:20Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16998

vishesh92 · 2026-03-05T06:59:04Z

@blueorangutan package

blueorangutan · 2026-03-05T07:00:04Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-03-05T07:52:47Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 17008

vishesh92 · 2026-03-10T06:51:37Z

@blueorangutan test keepEnv

blueorangutan · 2026-03-10T06:52:03Z

@vishesh92 a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2026-03-10T23:18:17Z

[SF] Trillian test result (tid-15588)
Environment: kvm-ol8 (x2), zone: Advanced Networking with Mgmt server ol8
Total time taken: 56416 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr12711-t15588-kvm-ol8.zip
Smoke tests completed. 146 look OK, 5 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_08_arping_in_ssvm	`Failure`	5.64	test_diagnostics.py
test_09_delete_kms_key	`Error`	11.03	test_kms_lifecycle.py
test_13_delete_hsm_profile	`Error`	7.53	test_kms_lifecycle.py
ContextSuite context=TestListIdsParams>:teardown	`Error`	1.13	test_list_ids_parameter.py
test_01_snapshot_root_disk	`Error`	6.22	test_snapshots.py
test_02_list_snapshots_with_removed_data_store	`Error`	52.65	test_snapshots.py
test_02_list_snapshots_with_removed_data_store	`Error`	52.65	test_snapshots.py
ContextSuite context=TestSnapshotStandaloneBackup>:teardown	`Error`	37.71	test_snapshots.py
test_01_snapshot_usage	`Error`	46.42	test_usage.py
test_01_vpn_usage	`Error`	1.36	test_usage.py

github-actions · 2026-03-13T21:12:34Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

sureshanaparti · 2026-03-23T09:02:07Z

api/src/main/java/com/cloud/event/EventTypes.java

+        entityEventDetails.put(EVENT_HSM_PROFILE_CREATE, HSMProfile.class);
+        entityEventDetails.put(EVENT_HSM_PROFILE_UPDATE, HSMProfile.class);
+        entityEventDetails.put(EVENT_HSM_PROFILE_DELETE, HSMProfile.class);
+


VOLUME.MIGRATE.TO.KMS event?

sureshanaparti · 2026-03-23T09:06:04Z

api/src/main/java/org/apache/cloudstack/api/command/admin/kms/MigrateVolumesToKMSCmd.java

+import java.util.List;
+
+@APICommand(name = "migrateVolumesToKMS",
+            description = "Migrates passphrase-based volumes to KMS (admin only)",


Suggested change

description = "Migrates passphrase-based volumes to KMS (admin only)",

description = "Migrates encrypted volumes to KMS",

not need of admin only, it's authorized, listed as admin's API

boring-cyborg bot added component:api component:build labels Feb 26, 2026

vishesh92 force-pushed the feature-kms branch from 0a283c9 to 5112eea Compare February 26, 2026 06:57

vishesh92 force-pushed the feature-kms branch from ceb2913 to d629f87 Compare February 26, 2026 07:39

vishesh92 requested a review from Copilot February 26, 2026 07:39

Copilot started reviewing on behalf of vishesh92 February 26, 2026 07:40 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

vishesh92 changed the title ~~Feature kms~~ Feature: Key Management Service (KMS) Feb 26, 2026

vishesh92 force-pushed the feature-kms branch from ba00a5d to 943f19a Compare February 26, 2026 12:39

apache deleted a comment from blueorangutan Feb 26, 2026

weizhouapache added this to the 4.23.0 milestone Feb 26, 2026

vishesh92 force-pushed the feature-kms branch 3 times, most recently from 8ea09bb to df2df4b Compare March 2, 2026 10:36

vishesh92 requested a review from Copilot March 2, 2026 11:40

Copilot started reviewing on behalf of vishesh92 March 2, 2026 11:41 View session

Copilot AI reviewed Mar 2, 2026

View reviewed changes

vishesh92 force-pushed the feature-kms branch 2 times, most recently from 75519c2 to 1fce0b2 Compare March 4, 2026 06:38

apache deleted a comment from blueorangutan Mar 5, 2026

vishesh92 requested a review from sureshanaparti March 5, 2026 12:23

github-actions bot added the status:has-conflicts label Mar 13, 2026

winterhazel added status:needs-testing status:needs-review labels Mar 17, 2026

vishesh92 mentioned this pull request Mar 18, 2026

Feature: Key Management Service (KMS) apache/cloudstack-documentation#634

Open

vishesh92 added 18 commits March 23, 2026 14:04

Add KMS framework

e995b46

integrate volume encryption with kms

e3a63ec

rotate keys wrapped with older versions

6079e0f

allow adding kms key in deploy vm

86e1d2b

temp commit

6abcffa

Add some tests

0d39a7b

fixups and some ui changes

f354da4

Change wrapping algo for pkcs

56cf3f6

fixups

529fd9d

fix list apis

6ba0af5

directly create the key in the store

bca1b25

Add missing license

d7c5e24

fixup

d8cdddb

Fix missing labels and label generation

949c00e

Fixup ui bug

1087503

fixups

0fe31fb

Add smoke test

30891ee

Fix test failures

2c49e92

vishesh92 force-pushed the feature-kms branch from fc55897 to 2c49e92 Compare March 23, 2026 08:44

sureshanaparti reviewed Mar 23, 2026

View reviewed changes

fixups

b68661c

	description = "Migrates passphrase-based volumes to KMS (admin only)",
	description = "Migrates encrypted volumes to KMS",

Conversation

vishesh92 commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Management Service (KMS) with HSM Integration

Description

New APIs

New Database Tables

New Global Settings

UI Changes

How to Test

Uh oh!

codecov bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

blueorangutan commented Feb 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vishesh92 commented Mar 4, 2026

Uh oh!

blueorangutan commented Mar 4, 2026

Uh oh!

blueorangutan commented Mar 4, 2026

Uh oh!

vishesh92 commented Mar 5, 2026

Uh oh!

blueorangutan commented Mar 5, 2026

Uh oh!

blueorangutan commented Mar 5, 2026

Uh oh!

vishesh92 commented Mar 10, 2026

Uh oh!

blueorangutan commented Mar 10, 2026

Uh oh!

blueorangutan commented Mar 10, 2026

Uh oh!

github-actions bot commented Mar 13, 2026

Uh oh!

sureshanaparti Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

sureshanaparti Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

vishesh92 commented Feb 26, 2026 •

edited

Loading

codecov bot commented Feb 26, 2026 •

edited

Loading